<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Incremental Building</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
  var popup = document.getElementById(material_id);
  popup.classList.toggle("show");
}
</script>

<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Incremental Building' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inbuildn.html">Inbuild Modules</a></li><li><a href="index.html">supervisor</a></li><li><a href="index.html#3">Chapter 3: Incremental Builds</a></li><li><b>Incremental Building</b></li></ul></div>
<p class="purpose">Deciding what is the least possible amount which needs to be built, in what order, to arrive at a working version of a copy.</p>

<ul class="toc"><li><a href="3-ib.html#SP1">&#167;1. Timestamps</a></li><li><a href="3-ib.html#SP5">&#167;5. Build process</a></li></ul><hr class="tocbar">

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Timestamps.</b>We want to assign a timestamp to every vertex in the graph, whose meaning is
that what it represents has been up-to-date since that time.
</p>

<p class="commentary">For a file vertex, we take that from the file system's timestamp. For a
copy vertex, we do the same for a copy which is a single file (such as an
extension), but for a copy which is a directory containing a composite of
resources, there's no good way to know. (Perhaps we could scan the files
in it recursively, but then we have to worry about hidden files, symlinks,
and all of that.) Instead, we use the build graph itself to decide; for
example, the timestamp for a kit is the most recent timestamp of any of its
binary Inter files, because those are its build-dependencies.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::timestamp</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::timestamp</span></span>:<br/><a href="3-ib.html#SP3">&#167;3</a>, <a href="3-ib.html#SP4">&#167;4</a>, <a href="3-ib.html#SP7_1_3_1">&#167;7.1.3.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">FILE_VERTEX:</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Filenames::timestamp</span><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">COPY_VERTEX:</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location_if_file</span><span class="plain-syntax">)</span>
<span class="plain-syntax">                </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Filenames::timestamp</span><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location_if_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-ib.html#SP3" class="function-link"><span class="function-syntax">IncrementalBuild::time_of_latest_build_dependency</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">default:</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">();</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>The following compares two times: it returns 1 if <span class="extract"><span class="extract-syntax">t1</span></span> is later, -1 if
<span class="extract"><span class="extract-syntax">t2</span></span> is later, and 0 if they are identical.
</p>

<p class="commentary">Note that we never apply the C standard library function <span class="extract"><span class="extract-syntax">difftime</span></span> in
the case of the never-time, which we consider to be before all other times.
(On most platforms it will be the C epoch of 1970, and <span class="extract"><span class="extract-syntax">difftime</span></span> alone
would be fine, but we're being careful.)
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::timecmp</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::timecmp</span></span>:<br/><a href="3-ib.html#SP3">&#167;3</a>, <a href="3-ib.html#SP4">&#167;4</a>, <a href="3-ib.html#SP7_1_3_1">&#167;7.1.3.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">t1</span><span class="plain-syntax">, </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">t2</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">t1</span><span class="plain-syntax"> == </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">()) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">t2</span><span class="plain-syntax"> == </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">()) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">return</span><span class="plain-syntax"> -1;</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">t2</span><span class="plain-syntax"> == </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">()) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">t1</span><span class="plain-syntax"> == </span><span class="identifier-syntax">t2</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">difftime</span><span class="plain-syntax">(</span><span class="identifier-syntax">t1</span><span class="plain-syntax">, </span><span class="identifier-syntax">t2</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> -1;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>We then take the latest timestamp of any build dependency:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::time_of_latest_build_dependency</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::time_of_latest_build_dependency</span></span>:<br/><a href="3-ib.html#SP1">&#167;1</a>, <a href="3-ib.html#SP7_1_3_1">&#167;7.1.3.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">latest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">();</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">build_edges</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">t</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP1" class="function-link"><span class="function-syntax">IncrementalBuild::timestamp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ib.html#SP2" class="function-link"><span class="function-syntax">IncrementalBuild::timecmp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">t</span><span class="plain-syntax">, </span><span class="identifier-syntax">latest</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">latest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">t</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">latest</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>And of any use dependency:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::time_of_latest_use_dependency</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::time_of_latest_use_dependency</span></span>:<br/><a href="3-ib.html#SP7_1_3_1">&#167;7.1.3.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">latest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">();</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">use_edges</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">t</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP1" class="function-link"><span class="function-syntax">IncrementalBuild::timestamp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ib.html#SP2" class="function-link"><span class="function-syntax">IncrementalBuild::timecmp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">t</span><span class="plain-syntax">, </span><span class="identifier-syntax">latest</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">latest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">t</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">latest</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. Build process.</b>This is a recursive process, beginning at the node representing what we want
to build. As we recurse, we pass a bitmap of the following:
</p>

<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">BUILD_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span><span class="plain-syntax"> </span><span class="comment-syntax"> We will need all your build dependencies too</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax"> </span><span class="constant-syntax">2</span><span class="plain-syntax"> </span><span class="comment-syntax"> We will need all your use dependencies too</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax"> </span><span class="constant-syntax">4</span><span class="plain-syntax"> </span><span class="comment-syntax"> Don't be incremental: trust nothing, rebuild everything</span>
<span class="definition-keyword">define</span> <span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax"> </span><span class="constant-syntax">8</span><span class="plain-syntax"> </span><span class="comment-syntax"> Don't be incremental: trust nothing, rebuild everything</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::build</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::build</span></span>:<br/>Copies - <a href="2-cps.html#SP12">&#167;12</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_methodology</span><span class="plain-syntax"> *</span><span class="identifier-syntax">meth</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-ib.html#SP7" class="function-link"><span class="function-syntax">IncrementalBuild::begin_recursion</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">BUILD_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">meth</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::rebuild</span><button class="popup" onclick="togglePopup('usagePopup6')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup6">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::rebuild</span></span>:<br/>Copies - <a href="2-cps.html#SP12">&#167;12</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_methodology</span><span class="plain-syntax"> *</span><span class="identifier-syntax">meth</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="3-ib.html#SP7" class="function-link"><span class="function-syntax">IncrementalBuild::begin_recursion</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">BUILD_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax"> + </span><span class="constant-syntax">IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">meth</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>This is called when Inbuild's <span class="extract"><span class="extract-syntax">-trace</span></span> switch is set at the command line.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">trace_ibg</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::enable_trace</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">trace_ibg</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>We want to be very sure that this recursion does not lock up, or perform
unnecessary work by performing the same node twice. To do this we apply the
<span class="extract"><span class="extract-syntax">built</span></span> flag to a node when it has been built; but to make this is not left
over from last time around, we only regard it when the <span class="extract"><span class="extract-syntax">last_built_in_generation</span></span> count
for the node is set to the current "generation", a unique number incremented
for each time we recurse.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">no_build_generations</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::begin_recursion</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::begin_recursion</span></span>:<br/><a href="3-ib.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">gb</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">build_methodology</span><span class="plain-syntax"> *</span><span class="identifier-syntax">BM</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">changes</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">T</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">trace_ibg</span><span class="plain-syntax">) </span><span class="identifier-syntax">T</span><span class="plain-syntax"> = </span><span class="identifier-syntax">STDOUT</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">no_build_generations</span><span class="plain-syntax">++;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Incremental build %d:\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">no_build_generations</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP7" class="function-link"><span class="function-syntax">IncrementalBuild::recurse</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">gb</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">BM</span><span class="plain-syntax">, &amp;</span><span class="identifier-syntax">changes</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">no_build_generations</span><span class="plain-syntax">, </span><a href="1-ic.html#SP16" class="function-link"><span class="function-syntax">Supervisor::shared_nest_list</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"%d change(s)\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">changes</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">IncrementalBuild::recurse</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">IncrementalBuild::recurse</span></span>:<br/><a href="3-ib.html#SP7_1_1">&#167;7.1.1</a>, <a href="3-ib.html#SP7_1_2">&#167;7.1.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">gb</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">V</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">build_methodology</span><span class="plain-syntax"> *</span><span class="identifier-syntax">BM</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> *</span><span class="identifier-syntax">changes</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">generation</span><span class="plain-syntax">, </span><span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">search_list</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Visit %c%c%c: "</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">BUILD_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">)?</span><span class="character-syntax">'b'</span><span class="plain-syntax">:</span><span class="character-syntax">'.'</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">)?</span><span class="character-syntax">'u'</span><span class="plain-syntax">:</span><span class="character-syntax">'.'</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">)?</span><span class="character-syntax">'i'</span><span class="plain-syntax">:</span><span class="character-syntax">'.'</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><a href="3-bg.html#SP6" class="function-link"><span class="function-syntax">Graphs::describe</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_built_in_generation</span><span class="plain-syntax"> == </span><span class="identifier-syntax">generation</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">build_result</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="named-paragraph-container code-font"><a href="3-ib.html#SP7_1" class="named-paragraph-link"><span class="named-paragraph">Build this node if necessary, setting rv to its success or failure</span><span class="named-paragraph-number">7.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">build_result</span><span class="plain-syntax"> = </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">last_built_in_generation</span><span class="plain-syntax"> = </span><span class="identifier-syntax">generation</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">rv</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7_1" class="paragraph-anchor"></a><b>&#167;7.1. </b>In everything which follows, <span class="extract"><span class="extract-syntax">rv</span></span> (prosaically, this stands only for "return
value") remains <span class="extract"><span class="extract-syntax">TRUE</span></span> until the first active step fails, at which point no
other active steps are ever taken, nor are any recursions made. In effect,
the first failure halts the process.
</p>

<p class="commentary">We are recursing depth-first, that is, we build the things needed to build
<span class="extract"><span class="extract-syntax">V</span></span> before we build <span class="extract"><span class="extract-syntax">V</span></span> itself.
</p>

<p class="commentary">A point of difference between this algorithm and <span class="extract"><span class="extract-syntax">make</span></span> is that we do not
halt with an error if a node has no way to be built. This is because the
graphs are here are built by Inbuild itself, not by a possibly erroneous
makefile whose author has forgotten something and whose intentions are not
clear. Here, if a node has no build script attached, it must be because it
needs no action taken.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Build this node if necessary, setting rv to its success or failure</span><span class="named-paragraph-number">7.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">inform_project</span><span class="plain-syntax"> *</span><span class="identifier-syntax">proj</span><span class="plain-syntax"> = </span><a href="5-ps2.html#SP9" class="function-link"><span class="function-syntax">Projects::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">as_copy</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">proj</span><span class="plain-syntax">) </span><span class="identifier-syntax">search_list</span><span class="plain-syntax"> = </span><a href="5-ps2.html#SP8" class="function-link"><span class="function-syntax">Projects::nest_list</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">proj</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) </span><span class="identifier-syntax">STREAM_INDENT</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">BUILD_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-ib.html#SP7_1_1" class="named-paragraph-link"><span class="named-paragraph">Build the build dependencies of the node</span><span class="named-paragraph-number">7.1.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="3-ib.html#SP7_1_2" class="named-paragraph-link"><span class="named-paragraph">Build the use dependencies of the node</span><span class="named-paragraph-number">7.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) </span><span class="identifier-syntax">STREAM_OUTDENT</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">rv</span><span class="plain-syntax">) &amp;&amp; (</span><a href="3-bg.html#SP5" class="function-link"><span class="function-syntax">Graphs::can_be_built</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">))) </span><span class="named-paragraph-container code-font"><a href="3-ib.html#SP7_1_3" class="named-paragraph-link"><span class="named-paragraph">Build the node itself, if necessary</span><span class="named-paragraph-number">7.1.3</span></a></span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-ib.html#SP7">&#167;7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP7_1_1" class="paragraph-anchor"></a><b>&#167;7.1.1. </b>Suppose V needs W (for whatever reason), and that W can only be used with X.
It follows that we will have to build X as well as W, since the process of
building V is itself a use of W, and therefore of X. So we always enable the
<span class="extract"><span class="extract-syntax">USE_DEPENDENCIES_MATTER_GB</span></span> bit when recursing through an edge.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Build the build dependencies of the node</span><span class="named-paragraph-number">7.1.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">b</span><span class="plain-syntax"> = </span><span class="identifier-syntax">gb</span><span class="plain-syntax"> | </span><span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">b</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">) </span><span class="identifier-syntax">b</span><span class="plain-syntax"> -= </span><span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">always_build_dependencies</span><span class="plain-syntax">) </span><span class="identifier-syntax">b</span><span class="plain-syntax"> |= </span><span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">build_edges</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">rv</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP7" class="function-link"><span class="function-syntax">IncrementalBuild::recurse</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">T</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">b</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">BM</span><span class="plain-syntax">, </span><span class="identifier-syntax">changes</span><span class="plain-syntax">, </span><span class="identifier-syntax">generation</span><span class="plain-syntax">, </span><span class="identifier-syntax">search_list</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-ib.html#SP7_1">&#167;7.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP7_1_2" class="paragraph-anchor"></a><b>&#167;7.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Build the use dependencies of the node</span><span class="named-paragraph-number">7.1.2</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">b</span><span class="plain-syntax"> = </span><span class="identifier-syntax">gb</span><span class="plain-syntax"> | </span><span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">b</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">) </span><span class="identifier-syntax">b</span><span class="plain-syntax"> -= </span><span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax"> *</span><span class="identifier-syntax">W</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">build_vertex</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">use_edges</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">rv</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP7" class="function-link"><span class="function-syntax">IncrementalBuild::recurse</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">OUT</span><span class="plain-syntax">, </span><span class="identifier-syntax">T</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">b</span><span class="plain-syntax"> | </span><span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">BM</span><span class="plain-syntax">, </span><span class="identifier-syntax">changes</span><span class="plain-syntax">, </span><span class="identifier-syntax">generation</span><span class="plain-syntax">, </span><span class="identifier-syntax">search_list</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-ib.html#SP7_1">&#167;7.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP7_1_3" class="paragraph-anchor"></a><b>&#167;7.1.3. </b>Now for the node <span class="extract"><span class="extract-syntax">V</span></span> itself.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Build the node itself, if necessary</span><span class="named-paragraph-number">7.1.3</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">needs_building</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">FOR_ONE_GENERATION_IGNORE_TIMESTAMPS_GB</span><span class="plain-syntax">) ||</span>
<span class="plain-syntax">        (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">always_build_this</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Ignoring timestamps and simply building: "</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><a href="3-bg.html#SP6" class="function-link"><span class="function-syntax">Graphs::describe</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">needs_building</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">never_build_this</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Ignoring timestamps and simply trusting: "</span><span class="plain-syntax">);</span>
<span class="plain-syntax">            </span><a href="3-bg.html#SP6" class="function-link"><span class="function-syntax">Graphs::describe</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">            </span><span class="named-paragraph-container code-font"><a href="3-ib.html#SP7_1_3_1" class="named-paragraph-link"><span class="named-paragraph">Decide based on timestamps</span><span class="named-paragraph-number">7.1.3.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">needs_building</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) { </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Build: "</span><span class="plain-syntax">); </span><a href="3-bg.html#SP6" class="function-link"><span class="function-syntax">Graphs::describe</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">); }</span>
<span class="plain-syntax">        (*</span><span class="identifier-syntax">changes</span><span class="plain-syntax">)++;</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">rv</span><span class="plain-syntax"> = </span><a href="3-bs.html#SP2" class="function-link"><span class="function-syntax">BuildScripts::execute</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">, </span><span class="identifier-syntax">V</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">script</span><span class="plain-syntax">, </span><span class="identifier-syntax">BM</span><span class="plain-syntax">, </span><span class="identifier-syntax">search_list</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) { </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"No build\n"</span><span class="plain-syntax">); }</span>
<span class="plain-syntax">    }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-ib.html#SP7_1">&#167;7.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP7_1_3_1" class="paragraph-anchor"></a><b>&#167;7.1.3.1. </b>This is where the incremental promise is finally kept. If the timestamp of
<span class="extract"><span class="extract-syntax">V</span></span> is definitely before later than that of everything it depends on, then
it would be redundant to recreate it.
</p>

<p class="commentary">Note that equal timestamps force rebuilding. File timestamping is quite coarse
on some systems, so equal timestamps might only mean that the two files were
created during the same second.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Decide based on timestamps</span><span class="named-paragraph-number">7.1.3.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">last_up_to_date_at</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP1" class="function-link"><span class="function-syntax">IncrementalBuild::timestamp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">last_up_to_date_at</span><span class="plain-syntax"> == </span><span class="identifier-syntax">Platform::never_time</span><span class="plain-syntax">())</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">needs_building</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) { </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Last built at: %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">ctime</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">last_up_to_date_at</span><span class="plain-syntax">)); }</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">BUILD_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">t</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP3" class="function-link"><span class="function-syntax">IncrementalBuild::time_of_latest_build_dependency</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">);</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) { </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Most recent build dependency: %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">ctime</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">t</span><span class="plain-syntax">)); }</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ib.html#SP2" class="function-link"><span class="function-syntax">IncrementalBuild::timecmp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">t</span><span class="plain-syntax">, </span><span class="identifier-syntax">last_up_to_date_at</span><span class="plain-syntax">) &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">)</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">needs_building</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">gb</span><span class="plain-syntax"> &amp; </span><span class="constant-syntax">USE_DEPENDENCIES_MATTER_GB</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">time_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">t</span><span class="plain-syntax"> = </span><a href="3-ib.html#SP4" class="function-link"><span class="function-syntax">IncrementalBuild::time_of_latest_use_dependency</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">V</span><span class="plain-syntax">);</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">T</span><span class="plain-syntax">) { </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"Most recent use dependency: %s\n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">ctime</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">t</span><span class="plain-syntax">)); }</span>
<span class="plain-syntax">            </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="3-ib.html#SP2" class="function-link"><span class="function-syntax">IncrementalBuild::timecmp</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">t</span><span class="plain-syntax">, </span><span class="identifier-syntax">last_up_to_date_at</span><span class="plain-syntax">) &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">)</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">needs_building</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">    }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="3-ib.html#SP7_1_3">&#167;7.1.3</a>.</li></ul>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="3-bm.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-sm.html">1</a></li><li class="progresschapter"><a href="2-gnr.html">2</a></li><li class="progresscurrentchapter">3</li><li class="progresssection"><a href="3-bg.html">bg</a></li><li class="progresssection"><a href="3-bm.html">bm</a></li><li class="progresscurrent">ib</li><li class="progresssection"><a href="3-bs.html">bs</a></li><li class="progresssection"><a href="3-bs2.html">bs2</a></li><li class="progresssection"><a href="3-is.html">is</a></li><li class="progresssection"><a href="3-is2.html">is2</a></li><li class="progresssection"><a href="3-is3.html">is3</a></li><li class="progresssection"><a href="3-is4.html">is4</a></li><li class="progresschapter"><a href="4-em.html">4</a></li><li class="progresschapter"><a href="5-es.html">5</a></li><li class="progresschapter"><a href="6-st.html">6</a></li><li class="progresschapter"><a href="7-tm.html">7</a></li><li class="progressnext"><a href="3-bs.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

